JS

The JS SDK for In-App Notifications provides a set of class methods to fetch and manipulate notifications

Installation

npm

npm install @sirenapp/js-sdk

yarn

yarn add @sirenapp/js-sdk

cdn

Add https://siren-js.sirenapp.io/siren-js-umd-sdk.js as a script

Usage

Initialize the SDK by creating a class instance as follows

import Siren from "@sirenapp/js-sdk"

const sirenInstance = new Siren({
        token: "your-user-token",
        recipientId: "your-recipient-id",
        onError: (error) => {
            // error callback function
        },
        actionCallbacks:{
            onEventReceive: (response: NotificationsApiResponse, eventType: 'NOTIFICATIONS'| 'UNVIEWED_COUNT') => {};
            onStatusChange: (status: 'SUCCESS' | 'FAILED' | 'PENDING') =>{};
        }
    });

All the exposed methods can be accessed using sirenInstance object. For example,to fetch all notifications,

const response = await sirenInstance.fetchAllNotifications({ page: 0, size: 10 });

Siren constructor accepts the following arguments

Property	Description	Type	Optional
token	User token	string	false
recipientId	Recipient id	string	false
onError	To receive error call backs when there is any error. Returns an error object of type, { Type: "ERROR", Message: "description of the error", Code: "error code specified in the error codes table" }	function	false
actionCallbacks	An object used to specify the callbacks triggered upon fetching the notifications or the unviewed count dynamically	object	true

Action callback keys

onEventReceive

This callback function is intended to handle data reception, which may come in two forms: either new notifications or the count of unviewed notifications. The function expects two parameters: response, which can be either of type NotificationsApiResponse or UnviewedCountResponse, and eventType, a string that can take values 'NOTIFICATIONS' or 'UNVIEWED_COUNT'

interface Notifications = {
    id: string;
    createdAt?: string;
    message: {
        channel: string;
        header: string;
        subHeader: string;
        body: string;
        actionUrl: string;
        avatar: {
            imageUrl: string;
            actionUrl: string | null;
        }
        additionalData: string;
    }
    requestId: string;
    isRead: boolean;
    sequenceNumber: number
}[]

interface UnviewedCount = {
    id: string;
    createdAt: string;
    updatedAt: string;
    deletedAt: string | null;
    createdBy: string;
    updatedBy: string;
    deletedBy: string | null;
    projectEnvironmentId: string;
    referenceId: string;
    providerIntegrationId: string;
    lastOpenedAt: string;
    totalUnviewed: number;
}

onStatusChange

Callback function to receive the verification status of recipient id and user toke, with status as an argument to the callback. Access to the methods will only be granted following successful verification.

enum VerificationStatus {
  PENDING = "PENDING",
  SUCCESS = "SUCCESS",
  FAILED = "FAILED",
}

Siren Methods

1. verifyToken

This method verifies the validity of the given tokens (recipientId and userToken).This method is called automatically while creating the instance . Once the verification is successful, the remaining exposed methods can be accessed.

await sirenInstance.verifyToken();

2. fetchUnviewedNotificationsCount

This method retrieves the count of unviewed notifications.

const { unviewedCount } = await sirenInstance.fetchUnviewedNotificationsCount();

3. fetchAllNotifications

This method retrieves list of notifications in a paginated manner.

const notifications = await sirenInstance.fetchAllNotifications({ page: 0, size: 15, sequenceNumber:start: 0, sequenceNumber:end: 0, isRead: false });

Argument	Description	Type	Optional	Default
page	Current page	number	true	0
size	Number of items fetched	number	true	10
sequenceNumber:start	Accepts a sequence number and retrieves notifications with sequence numbers greater than or equal to the given number. By default, only the first 20 notifications will be fetched	number	true	null
sequenceNumber:end	Accepts a sequence number and retrieves notifications with sequence numbers less than the given number. By default, only the first 20 notifications will be fetched	number	true	null
isRead	Filter to fetch read or unread notifications. If not specified, it retrieves both read and unread notifications	boolean	true	null

Response

 interface Notifications = {
    id: string;
    createdAt?: string;
    message: {
        channel: string;
        header: string;
        subHeader: string;
        body: string;
        actionUrl: string;
        avatar: {
            imageUrl: string;
            actionUrl: string | null;
        }
        additionalData: string;
    }
    requestId: string;
    isRead: boolean;
    sequenceNumber: number
}[]

4. startRealTimeFetch

By specifying the parameter eventType as either NOTIFICATIONS or UNVIEWED_COUNT, this method triggers the real-time retrieval of notifications or the count of unviewed notifications. If NOTIFICATIONS is selected, further parameters (params) can be provided for additional customization or filtering

sirenInstance.startRealTimeFetch({
  eventType: NOTIFICATIONS,
  params: { page: 0, size: 15, start: '', end: '', isRead: false }
});

sirenInstance.startRealTimeFetch({ eventType: UNVIEWED_COUNT });

The notifications received can be subscribed using the onEventReceive actionCallback. The parameters for the params object are as follows:

Argument	Description	Type	Optional	Default
page	Represents the current page	number	true	0
size	Represents the number of items to be fetched in a single call	number	true	10
sequenceNumber:start	Accepts a sequence number and retrieves notifications with sequence numbers greater than or equal to the given number. By default, only the first 20 notifications will be fetched	number	true	null
sequenceNumber:end	Accepts a sequence number and retrieves notifications with sequence numbers less than the given number. By default, only the first 20 notifications will be fetched	number	true	null
isRead	Filter to fetch read or unread notifications. If not specified, it retrieves both read and unread notifications	boolean	true	null

5. stopRealTimeFetch

By specifying the parameter eventType as either NOTIFICATIONS or UNVIEWED_COUNT, this method stops the real-time retrieval of notifications or the count of unviewed notifications.

sirenInstance.stopRealTimeFetch(NOTIFICATIONS);


sirenInstance.stopRealTimeFetch(UNVIEWED_COUNT);

6. markAsReadById

This method marks the notification as read. It accepts a notification id as an argument.

await sirenInstance.markAsReadById('your-notification-id');

7. markAsReadByDate

This method marks the notifications as read till the given date.
It accepts an ISO date string as an argument.

await sirenInstance.markAsReadByDate('2011-10-05T14:48:00.000Z');

8. deleteById

This method deletes a notification. It accepts a notification id as an argument.

await sirenInstance.deleteById('your-notification-id');

9. deleteByDate

This method deletes the notifications till the given date.
It accepts an ISO date string as an argument

await sirenInstance.deleteByDate('2011-10-05T14:48:00.000Z');

10. markAllAsViewed

This method marks the notifications as viewed till the given date. This sets the unviewed count as 0
It accepts an ISO date string as an argument

await sirenInstance.markAllAsViewed('2011-10-05T14:48:00.000Z');

Error codes

Given below are the possible error codes thrown by sdk

Error code	Description
INVALID_CREDENTIALS	The credentials provided are not valid
AUTHENTICATION_FAILED	Failed to authenticate given credentials
UNAUTHORIZED_OPERATION	Attempting to invoke methods using invalid credentials
INVALID_ERROR_FUNCTION	The provided error function is invalid
AUTHENTICATION_PENDING	Token verification is in progress
INVALID_CALLBACK_FUNCTION	The callback function provided within actionCallbacks is not valid
MISSING_PARAMETER	The required parameter is missing
NOTIFICATION_FETCH_FAILED	Failed to fetch notifications
UNVIEWED_COUNT_FETCH_FAILED	Failed to fetch unviewed notifications count
MARK_AS_READ_FAILED	Failed to mark notification as read
DELETE_FAILED	Failed to delete notification
MARK_ALL_AS_VIEWED_FAILED	Failed to mark notification as viewed
BULK_DELETE_FAILED	Bulk deletion of notifications failed
MARK_ALL_AS_READ_FAILED	Failed to mark all notifications as read

Example

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script src="https://siren-js.sirenapp.io/siren-js-umd-sdk.js"></script>
  </head>

  <body>
    <div class="container">
        <h1>CDN Client</h1>
        <div class="wrapper">
            <button class="button" onclick="getUnviewedCount()">FETCH UNVIEWED COUNT</button>
            <button class="button" onclick="getAllNotifications()">FETCH ALL NOTIFICATIONS</button>
            <button class="button" onclick="markAsViewed()">MARK AS VIEWED</button>
        </div>
        <div class="wrapper">
            <button class="button" onclick="markAsReadById()">MARK AS READ BY ID</button>
            <button class="button" onclick="markAllAsRead()">MARK ALL AS READ</button>
        </div>
        <div class="wrapper">
            <button class="button" onclick="deleteById()">DELETE BY ID</button>
            <button class="button" onclick="clearAll()">CLEAR ALL</button>
        </div>
        <div class="wrapper">
            <button class="button" onclick="startNotificationsRealTimeFetch()">START REAL TIME NOTIFICATION FETCH</button>
            <button class="button" onclick="stopNotificationsRealTimeFetch()">STOP REAL TIME NOTIFICATION FETCH</button>
        </div>
        <div class="wrapper">
            <button class="button" onclick="startUnviewedCountRealTimeFetch()">START REAL TIME COUNT FETCH</button>
            <button class="button" onclick="stopUnviewedCountRealTimeFetch()">STOP REAL TIME COUNT FETCH</button>
        </div>
    </div>
    </body>
    <script>
    var sirenWeb;

    const recipientToken = 'YOUR_RECIPIENT_TOKEN';
    const recipientID = 'YOUR_RECIPIENT_ID';
    const notificationId = 'NOTIFICATION_ID';

    if (Siren) {
        sirenWeb = new Siren({
        token: recipientToken,
        recipientId: recipientID,
        onError: (error) => {
            console.log('Error callback:', error);
        },
        actionCallbacks: {
            onEventReceive: (response, eventType) => {
            if(eventType === 'NOTIFICATIONS' && response.data.length > 0)
                document.getElementById("output").innerHTML = 'New Notifications ' + JSON.stringify(response, null, 2);
            else if(eventType === 'UNVIEWED_COUNT' && response.data)
                document.getElementById("output").innerHTML = 'Latest unviewed count ' + JSON.stringify(response, null, 2);
            }
        }});
    }
    function startNotificationsRealTimeFetch() {
        sirenWeb.startRealTimeFetch({eventType: 'NOTIFICATIONS', params: { page: 0, size: 10 }});
    }
    function stopNotificationsRealTimeFetch() {
        sirenWeb.stopRealTimeFetch('NOTIFICATIONS');
    }
    async function markAsReadById() {
        const res = await sirenWeb.markAsReadById(notificationId);
    }
    async function markAllAsRead() {
        const res= await sirenWeb.markAsReadByDate(new Date().toISOString());
    }
    async function deleteById() {
        const res= await sirenWeb.deleteById(notificationId);
    }
    async function clearAll() {
        const res = await sirenWeb.deleteByDate(new Date().toISOString());
    }
    async function markAsViewed() {
        const res = await sirenWeb.markAllAsViewed(new Date().toISOString());
    }
</script>

</html>